2.1 Accessing the API documentation

The API documentation is provided on the API server at the following address:

https://<myserver>/rest.core/swagger/index.html

where <myserver> is the name of the server hosting the web service.

If necessary, you can configure the API documentation to prevent access. You can also to configure the API documentation to provide details of error codes, and to allow you to use the documentation as a test harness, subject to the appropriate authentication.

To configure access the API documentation:

1. In a text editor, open the appsettings.Production.json file for the web service.

   By default, this is:

   C:\Program Files\Intercede\MyID\rest.core\appsettings.Production.json

   This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file, and include the following:

   Copy

   {
     "MyID":  {
       "SwaggerApiDocumentation":  {
         "GenerateDocumentation":  true,
         "DocumentErrorCodes":  false,
         "DocumentMIReports":  true,
         "AllowTestFromDocumentation":  false,
         "ShowPermissions":  false
       }
     }
   }

   If the appsettings.Production.json file already exists, add the above SwaggerApiDocumentation section to the file.

2. Edit the following values:

   • GenerateDocumentation – set to false to prevent access to the documentation.

   • DocumentErrorCodes – set to true to include details of the web service error messages associated with HTTP status codes.

     Note: If you are consuming the Swagger output using an external tool, you may experience compatibility issues if you set this value to true; set DocumentErrorCodes to false to prevent this.

   • DocumentMIReports – set to true to include details of Management Information reports.

   • AllowTestFromDocumentation – set to true to allow you to use the documentation as a test harness, subject to the appropriate authentication. When you enable this option, the API documentation provides authentication instructions at the top of the page; see also section 5.2, Calling the API from the documentation.

   • ShowPermissions – set to true to display the permissions required for each API call. See section 2.2, Accessing the API features for more information.

3. Save the appsettings.Production.json file.

4. Recycle the web service app pool:

   1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
   2. Right-click the myid.rest.core.pool application pool, then from the pop-up menu click Recycle.

   This ensures that the web service has picked up the changes to the configuration file.

5. Open a web browser, and navigate to the following URL:

   https://<myserver>/rest.core/swagger/index.html

   where <myserver> is the name of the server hosting the web service.